=============
Configuration
=============

SYNTAX
======

The configuration file consists of statements and comments, each of
which must be on a line of its own. Comments start with a "#". Leading
and trailing whitespace is ignored; so are empty lines, but they may
*not* contain other whitespace.


STATEMENTS
==========

.. confvar:: account [login@]host

    Subsequent statements only apply to accounts matching `login` and `host`.
    If `login` is omitted, all accounts on `host` match.

.. confvar:: alias string

    Use `string` as alias for the current host.

.. confvar:: backups n

    Keep `n` backups of Sieve scripts.

    `n` = 0
        Do not make backups (default).

    `n` = 1
        Back up :file:`file` as :file:`file~`.

    `n` > 1
        Back up :file:`file` as :file:`file.~{m}~`, where
        *m* starts with 1 and increments with each backup.

.. confvar:: cafile file

    Load custom certificate authorities (CAs) from `file`.
    `file` must be in PEM format.

.. confvar:: cadir dir

    Load custom certificate authorities (CAs) from `dir`. `Dir` must
    contain one PEM file per CA, each of which must be named after the
    hash of its subject name.

    .. only:: man

        See :manpage:`c_rehash(1)` for details.

    .. only:: html

        See the OpenSSL manual (fn. SSL_CTX_load_verify_locations_)
        for more information.

.. confvar:: cert file

    Read the client TLS certificate from `file`. `file` must be in PEM
    format and contain the private key, the client certificate, and every
    CA certificate required to establish the certificate's authenticity,
    in that order. Some ManageSieve servers also require that each CA
    certificate is followed by its certificate revocation list.

.. confvar:: confirm command [, ...]

    Comma-separated list of commands that require confirmation
    if they overwrite or remove a file.

    Either a combination of:

    * :sievecmd:`cp`
    * :sievecmd:`get`
    * :sievecmd:`mv`
    * :sievecmd:`put`
    * :sievecmd:`rm`

    Or one of:

    * ``all`` (default)
    * ``none``

.. confvar:: getpassphrase command

    Read the TLS key passphrase from the standard output of :samp:`{command}`.

.. confvar:: getpassword command

    Read the login password from the standard output of :samp:`{command}`.

.. confvar:: host hostname|internet address

    Host to connect to (default: :samp:`localhost`).

.. confvar:: key file

    Read the client TLS key from `file`, rather than from the certificate file.
    `file` must be in PEM format.

.. confvar:: login username

    Log in as *username*.

.. confvar:: ocsp boolean

    Check whether the server's TLS certificate has been revoked?

    ``yes`` (default) or ``no``.

    .. danger::
        Only disable if the issuer of the server's TLS
        certificate does not provide an OCSP_ responder.

.. confvar:: password password

     Use `password` to log in.

     .. danger::
         Passwords should be stored in encrypted form only.
         Use :confvar:`getpassword` instead (see `Password managers`_ below).

.. confvar:: port port

    Connect to `port` (default: 4190).

.. confvar:: timeout float

    Connection timeout in seconds.

.. confvar:: tls boolean

    Secure connections with Transport Layer Security (TLS)?

    ``yes`` (default) or ``no``.

    .. danger::
        Data sent over an unsecured connection can be
        read and modified by third parties.

.. confvar:: saslmechs mechanism [, ...]

    Comma-separated list of authentication mechanisms, ordered by preference.

    Either a combination of password-based mechanisms:

    * ``scram-sha3-512-plus``
    * ``scram-sha-512-plus``
    * ``scram-sha-384-plus``
    * ``scram-sha-256-plus``
    * ``scram-sha-224-plus``
    * ``scram-sha-1-plus``
    * ``scram-sha3-512``
    * ``scram-sha-512``
    * ``scram-sha-384``
    * ``scram-sha-256``
    * ``scram-sha-224``
    * ``scram-sha-1``
    * ``plain``
    * ``cram-md5`` (obsolete)
    * ``login`` (obsolete)

    Or:

    * ``external``

    Shell-like patterns are expanded to mechanisms in the above order.

    Default: ``scram-*, plain``

.. confvar:: saslprep credentials

    Which `credentials` to normalise.

    One of:

    * ``usernames``
    * ``passwords``
    * ``all`` (default)
    * ``none``

    Adjust if valid credentials are rejected.

.. confvar:: verbosity level

    One of:

    * ``error``
    * ``warning``
    * ``info`` (default)
    * ``debug``
    * ``auth`` (show authentication exchange)

    The higher the level, the fewer messages are printed,
    where ``error`` is highest and ``auth`` lowest.

    .. danger::
        The authentication exchange contains your password,
        even though this is not apparent.

.. confvar:: x509strict boolean

    Reject TLS certificates that do not conform to :RFC:`5280`?

    ``yes`` (default) or ``no``.


FILENAME VARIABLES
==================

Relative filenames are interpreted as relative to the directory that the
configuration file is in or, if a filename is given with :option:`-o`,
as relative to the current working directory.


WORD EXPANSION
==============

:samp:`~`, :samp:`~{user}`, :code:`$var`, and :code:`$\{var\}` are
expanded in commands and filenames.

:samp:`~` and :samp:`~{user}` are expanded to the home directory of the
current and the given `user` respectively, but only if they occur at
the start of a word.

:code:`$var` and :code:`$\{var\}` are expanded to the configuration
variable `var`. '\$' can be escaped by prefixing it with an additional
'\$' (e.g., :code:`$$var` is expanded to :code:`$var`).

Commands are split into words before '~' and variables are expanded.
Filenames are not subject to word-splitting.


FILES
=====

:file:`/etc/sieve/config`, :file:`/etc/sieve.cf`, :file:`{$XDG_CONFIG_HOME}/sieve/config`, :file:`{$HOME}/.sieve/config`, :file:`{$HOME}/.sieve.cf`
    Default configuration file locations.


EXAMPLES
========

Recommended configuration
-------------------------

.. code:: none

    # Keep a single backup
    backups 1

    # Only require confirmation for removing scripts
    confirm rm

    # Be less verbose
    verbosity warning

    # Accounts
    account imap.foo.example
        alias foo
        login user

    account imap.bar.example
        alias bar
        login user@bar.example


Password managers
-----------------

Lookup passwords stored by Apple Mail or MailMate_ in macOS' Keychain:

.. code:: none

    getpassword security find-internet-password -s$host -a$login -w


GnuPG-encrypted files
---------------------

GnuPG_ can be used as password manager.

Encrypt the password for the user :samp:`user` on :samp:`imap.foo.example`
using the key with the ID :samp:`0123456789abcdef` and save the encrypted
password in :file:`~/secret/user@imap.foo.example.gpg`:

.. code:: none

    $ gpg -er 0123456789abcdef <<EOF >~/secret/user@imap.foo.example.gpg
    > v3ry!s3cr3t!p8ssw0rd! 
    > EOF

This password can then be used with:

.. code:: none

    getpassword gpg -d ~/secret/$login@$host.gpg


TLS authentication
------------------

Use TLS authentication to login as :samp:`user`
on :samp:`imap.foo.example`:

.. code:: none

    account imap.foo.example
        login user
        cert client.crt
        key client.key
        saslmechs external


.. only:: man

    SEE ALSO
    ========

    :manpage:`sievemgr(1)`

